home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / CW GUSI 1.6.4 / doc / pod / GUSI_Advanced.pod next >
Text File  |  1995-04-07  |  10KB  |  307 lines
  1. =head1 Advanced techniques
  2.  
  3. This section discusses a few techniques that probably not
  4. every user of C<GUSI> needs.
  5.  
  6. =head2 FSSpec routines
  7.  
  8. If you need to do complicated things with the Mac file system,
  9. the normal C<GUSI> routines are probably not sufficient, but you still might
  10. want to use the internal mechanism C<GUSI> uses. This mechanism is provided in
  11. the header file C<TFileSpec.h>, which defines both C<C> and C<C++> interfaces.
  12. In the following, the C<C++> member functions will be discussed and C<C> equivalents
  13. will be mentioned where available.
  14.  
  15. C<OSErr TFileSpec::Error()> returns the last error provoked by a C<TFileSpec> member
  16. function.
  17.  
  18. C<TFileSpec::TFileSpec(const FSSpec & spec, Boolean useAlias = false)> constructs
  19. a C<TFileSpec> from an C<FSSpec> and resolves alias files unless C<useAlias> is C<true>.
  20. (The C<useAlias> parameter is also present in the following routines, but will not
  21. be shown anymore).
  22.  
  23. C<TFileSpec(short vRefNum, long parID, ConstStr31Param name)>
  24. constructs a C<TFileSpec> from its components.
  25.  
  26. C<TFileSpec(short wd, ConstStr31Param name)> constructs
  27. a C<TFileSpec> from a working directory reference number and a path component. 
  28.  
  29. This routine is available to C<C> users as 
  30. C<OSErr WD2FSSpec(short wd, ConstStr31Param name, FSSpec * desc)>.
  31.  
  32. C<TFileSpec(const char * path)> constructs a 
  33. C<TFileSpec> from a full or relative path name. 
  34. This routine is available to C<C> users as 
  35. C<OSErr Path2FSSpec(const char * path, FSSpec * desc)>.
  36.  
  37. C<TFileSpec(OSType object, short vol = kOnSystemDisk, long dir = 0)> constructs 
  38. special C<TFileSpec>s, depending on C<object>. 
  39.  
  40. This routine is available to C<C> users as 
  41. C<OSErr Special2FSSpec(OSType object, short vol, long dirID, FSSpec * desc)>.
  42.  
  43. All constants in C<Folders.h> acceptable
  44. for C<FindFolder()> can be passed, e.g. the following:
  45.  
  46. =over 4
  47.  
  48. =item kSystemFolderType       
  49.  
  50.  The system folder.
  51.  
  52. =item kDesktopFolderType      
  53.  
  54.  The desktop folder; objects in this folder show on the desk top.
  55.  
  56. =item kExtensionFolderType    
  57.  
  58.  Finder extensions go here.
  59.  
  60. =item kPreferencesFolderType  
  61.  
  62.  Preferences for applications go here.
  63.  
  64. =back
  65.  
  66. Furthermore, the value C<kTempFileType> is defined, which creates a temporary
  67. file in the temporary folder, or, if C<dir> is nonzero, in the directory you
  68. specify.
  69.  
  70. C<TFileSpec(short fRefNum)> constructs a C<TFileSpec> from the file reference 
  71. number of an open file. 
  72.  
  73. In principle, a C<TFileSpec> should be compatible with an C<FSSpec>. However, to
  74. be absolutely sure, you can call C<TFileSpec::Bless()> which will call 
  75. C<FSMakeFSSpec()> before passing the TFileSpec to a C<FSp> file system routine.
  76.  
  77. C<char * TFileSpec::FullPath()> returns the full path name of the file. The
  78. address returned points to a static buffer, so it will be overwritten on
  79. further calls.
  80. This routine is available to C<C> users as 
  81. C<char * FSp2FullPath(const FSSpec * desc)>.
  82.  
  83. C<char * TFileSpec::RelPath()> works like C<FullPath()>, but when the current 
  84. folder given by C<chdir()> is a pparent folder of the object, a relative path
  85. name will be returned. The address returned points to a static buffer, so it 
  86. will be overwritten on further calls.
  87. This routine is available to C<C> users as 
  88. C<char * FSp2RelPath(const FSSpec * desc)>.
  89.  
  90. C<char * TFileSpec::Encode()> returns an ASCII encoding which may be passed 
  91. to all C<GUSI> routines taking path names. The address returned points to a 
  92. static buffer, so it will be overwritten on further calls. This generates 
  93. short names which may be parsed rather quickly.
  94. This routine is available to C<C> users as 
  95. C<char * FSp2Encoding(const FSSpec * desc)>.
  96.  
  97. C<OSErr  TFileSpec::CatInfo(CInfoPBRec & info, Boolean dirInfo = false)> Gives 
  98. information about the current object. If C<dirInfo> is C<true>, gives information 
  99. about the current object's directory.
  100. This routine is available to C<C> users as 
  101. C<OSErr FSpCatInfo(const FSSpec * desc, CInfoPBRec * info)>.
  102.  
  103. C<OSErr TFileSpec::Resolve(Boolean gently = true)> resolve the object if it is an alias file.
  104. If gently is C<true> (the default), nonexisting files are tolerated.
  105.  
  106. C<Boolean TFileSpec::Exists()> returns C<true> if the object exists.
  107.  
  108. C<Boolean TFileSpec::IsParentOf(const TFileSpec & other)> returns C<true> if the object is
  109. a parent of C<other>.
  110.  
  111. C<TFileSpec TFileSpec::operator--()> replaces the object with its parent directory.
  112. This routine is available to C<C> users as 
  113. C<OSErr FSpUp(FSSpec * desc)>.
  114.  
  115. C<TFileSpec FileSpec::operator-=(int levels)> is equivalent to calling C<--> 
  116. C<levels> times and C<TFileSpec FileSpec::operator-(int levels)> is equivalent
  117. to calling C<-=> on a I<copy> of the current object.
  118.  
  119. C<TFileSpec TFileSpec::operator+=(ConstStr31Param name)>, 
  120. C<TFileSpec TFileSpec::operator+=(const char * name)>, and their non-destructive 
  121. counterparts C<+> add a further component to the current object, which must be
  122. an existing directory.
  123.  
  124. This routine is available to C<C> users as 
  125. C<OSErr FSpDown(FSSpec * desc, ConstStr31Param name)>.
  126.  
  127. C<TFileSpec TFileSpec::operator[](short index)> returns the C<index>th object in
  128. the parent folder of the current object.
  129.  
  130. A destructive version of this routine is available to C<C> users as 
  131. C<OSErr FSpIndex(FSSpec * desc, short index)>.
  132.  
  133. Furthermore, the C<==> and C<!=> operators are defined to test C<TFileSpec>s for
  134. equality.
  135.  
  136. C<OSErr FSpSmartMove(const FSSpec * from, const FSSpec * to)> does all the work
  137. of moving and renaming a file (within the same volume), handling (I hope) all 
  138. special cases (You might be surprised how many there are).
  139.  
  140. =head2 File pattern iterators
  141.  
  142. Sometimes you might find it useful to find all files ending in C<.h> or all
  143. directories starting with C<MW>. For this purpose, C<GUSI> offers a mechanism
  144. in the header file C<TFileGlob.h>, which defines both C<C> and C<C++> interfaces.
  145.  
  146. You start a search by constructing a file pattern iterator with
  147. C<TFileGlob::TFileGlob(const char * pattern, const TFileSpec * startDir = nil)>.
  148. C<pattern> is an absolute or relative path name, with the following characters
  149. getting a special interpretation:
  150.  
  151. =over 4
  152.  
  153. =item C<?>
  154.  
  155. Matches an arbitrary single character. 
  156.  
  157. =item C<*>
  158.  
  159. Matches any number of characters (including none).
  160.  
  161. =item C<\>
  162.  
  163. Suppresses the special interpretation of the following character.
  164.  
  165. =back
  166.  
  167. C<startDir> provides a nonstandard starting directory for relative patterns.
  168.  
  169. After you have constructed the iterator, you can check whether a file was found
  170. by calling C<Boolean TFileGlob::Valid()>. If one was found, you can use the
  171. <TFileGlob> instance as a <TFileSpec> and thus as a <FSSpec>. To get the next
  172. file, call C<Boolean TFileGlob::Next()>, which again returns C<true> if another
  173. match was found.
  174.  
  175. To call the file pattern iterator routines from C<C>, you have the following
  176. routines: 
  177.  
  178. =over 4
  179.  
  180. =item C<FileGlobRef NewFileGlob(const char * pattern)> 
  181.  
  182. Constructs an iterator.
  183.  
  184. =item C<Boolean NextFileGlob(FileGlobRef glob)> 
  185.  
  186. Advances the iterator. 
  187.  
  188. =item C<Boolean FileGlob2FSSpec(FileGlobRef glob, FSSpec * spec)> 
  189.  
  190. Copies the file specification to C<spec> and returns whether the iterator is valid.
  191.  
  192. =item C<void DisposeFileGlob(FileGlobRef glob)> 
  193.  
  194. Destructs the iterator.
  195.  
  196. =back 
  197.  
  198. =head2 Adding your own socket families
  199.  
  200. It is rather easy to add your own socket
  201. types to C<GUSI>:
  202.  
  203. =over 4
  204.  
  205. =item *
  206.  
  207. Pick an unused number between 17 and C<GUSI_MAX_DOMAINS> to use for your address family.
  208.  
  209. =item *
  210.  
  211. Include C<GUSI_P.h>.
  212.  
  213. =item *
  214.  
  215. Write a subclass of C<SocketDomain> and override C<socket()> and optionally C<choose()>.
  216.  
  217. =item *
  218.  
  219. Write a subclass of C<Socket> and override whatever you want. If you override
  220. C<recvfrom()> and C<sendto()>, C<read()> and C<write()> are automatically defined.
  221.  
  222. =item *
  223.  
  224. For more information, study the code in C<GUSIDispatch.cp> and C<GUSISocket.cp>,
  225. which implement the generic socket code. The easiest actual socket implementation
  226. to study is probably C<GUSIUnix.cp>.
  227.  
  228. =back
  229.  
  230. =head2 Adding your own file families
  231.  
  232. C<GUSI> also supports adding special treatment for
  233. certain file names to almost all (tell me if I have forgotten one) standard C<C> library 
  234. routines dealing with file names. To avoid countless rescanning of file names, C<GUSI>
  235. preprocesses the names:
  236.  
  237. =over 4
  238.  
  239. =item *
  240.  
  241. If the file name starts with C<"Dev:"> (case insensitive), the file name is considered
  242. a I<device name>, and the rest of the name can have any structure you like.
  243.  
  244. =item *
  245.  
  246. Otherwise, the name is translated into a C<FSSpec>, and therefore should refer to a real
  247. file system object (all intermediate path name components should refer to existing
  248. directories).
  249.  
  250. =back
  251.  
  252. To create a file family:
  253.  
  254. =over 4
  255.  
  256. =item *
  257.  
  258. Pick an address family, as described above. However, if you don't plan on creating sockets
  259. of this family with socket(), just specify C<AF_UNSPEC>.
  260.  
  261. =item *
  262.  
  263. Include C<GUSIFile_P.h>.
  264.  
  265. =item *
  266.  
  267. Write a subclass of C<FileSocketDomain>, specifying whether you are interested in device 
  268. names, file names, or both, and override C<Yours()> and other calls.
  269.  
  270. =item *
  271.  
  272. Write a subclass of C<Socket> and override whatever you want.
  273.  
  274. =item *
  275.  
  276. For more information, study the code in C<GUSIFile.cp>, which implements the generic 
  277. file socket code.
  278.  
  279. =back
  280.  
  281. In your C<Yours()> member function, you specify whether you are prepared to handle
  282. one of the following functions for a given file name:
  283.  
  284.     enum Request {
  285.       willOpen,
  286.       willRemove,
  287.       willRename,
  288.       willGetFileInfo,
  289.       willSetFileInfo,
  290.       willFAccess,
  291.       willStat,
  292.       willChmod,
  293.       willUTime,
  294.         willAccess
  295.     };
  296.  
  297. If you return C<true> for a request, your corresponding member function will be called.
  298. Member functions are similar to the corresponding C<C> library functions, except that
  299. their first parameter is a C<GUSIFileRef &> instead of a C<const char *> (but further
  300. file name parameters, as in C<rename()>, will be left untouched). You might also return
  301. C<true> but I<not> override the member function to indicate that standard file treatment 
  302. (C<EINVAL> for many routines) is OK.
  303.  
  304. The member function will always be called immediately after the C<Yours()> function, so
  305. you may want to pre-parse the file name in the C<Yours()> function and keep the information
  306. for the member function.
  307.